$ cd NEW_PLUGIN # for example
$ git remote rename origin old-origin
$ git remote add origin git@gitlab.dkrz.de:freva/plugins4freva/new_plugin.git
$ git push -u origin --all
$ git push -u origin --tags

$ module load r

$ which R

# Start and R command line session
$ R

output_file='$USER_OUTPUT_DIR/myfile_${SYSTEM_DATETIME}blah.nc'

class PluginAbstract(abc.ABC):
    """Base class that is used as a template for all Freva plugins.
    Any api wrapper class defining Freva plugins must inherit from this class."""

    @deprecated_method("PluginAbstract", "class_basedir")
    def getClassBaseDir(self) -> Optional[str]:
        """Deprecated method for class_basedir."""

    def class_basedir(self) -> str:
        """Get absolute path to the module defining the plugin class."""

class PluginAbstract(abc.ABC):
    """Base class that is used as a template for all Freva plugins.
    Any api wrapper class defining Freva plugins must inherit from this class."""

    def call(
        self,
        cmd_string: Union[str, list[str]],
        check: bool = True,
        **kwargs,
    ) -> sub.Popen[Any]:
        """Run command with arguments and return a CompletedProcess instance."""

from evaluation_system.api import plugin
class TemplatePlugin(plugin.PluginAbstract):
    def run_tool(self, config_dict=None)
        self.call(
            f"{self.class_basedir}/main_code.sh {config_dict}"
        )
        # or
        self.call(
            f"{Path(__file__).parent}/main_code.sh {config_dict}"
        )
        # or
        self.call(
            f"{os.getenv(USER_BASE_DIR)}/main_code.sh {config_dict}"
        )

class PluginAbstract(abc.ABC):
    @deprecated_method("PluginAbstract", "add_output_to_databrowser")
    def linkmydata(self, *args, **kwargs):  # pragma: no cover

    def add_output_to_databrowser(
        self,
        plugin_output: os.PathLike,
        project: str, # user-<user-id>
        product: str, # project.product
        *,
        model: str = "freva",
        institute: Optional[str] = None,
        ensemble: str = "r1i1p1",
        time_frequency: Optional[str] = None,
        variable: Optional[str] = None,
        experiment: Optional[str] = None,
        index_data: bool = True,
    ) -> Path:

from evaluation_system.api import plugin
class TemplatePlugin(plugin.PluginAbstract):
    def run_tool(self, config_dict=None)
        self.add_output_to_databrowser(
            plugin_output=config_dict["outputdir"],
            project=config_dict.get("project", "default_project"),
            product=config_dict.get("product", "default_product"),
            model=config_dict.get("model", "default_model"),
            institute=config_dict.get("institute", "default_institute"),
            time_frequency="mon",
        )

class PluginAbstract(abc.ABC):
    """Base class that is used as a template for all Freva plugins.
    Any api wrapper class defining Freva plugins must inherit from this class."""

    @deprecated_method("PluginAbstract", "prepare_output")
    def prepareOutput(self, *args) -> dict[str, dict[str, str]]:
        """Deprecated method for :class:`prepare_output`. """

    def prepare_output(
        self, output_files: Union[str, list[str], dict[str, dict[str, str]]]
    ) -> dict[str, dict[str, str]]:
        """Prepare output for files supposedly created."""

from evaluation_system.api import plugin
class TemplatePlugin(plugin.PluginAbstract):
    def run_tool(self, config_dict=None)
        return self.prepare_output(config_dict["outputdir"])

class ParameterType(initOrder):
    """Base class for all parameter types.
    All available parameter types inherit from this class. The class creates
    a parameter object holding the following user defined information.
    """
    def __init__(
        self,
        name=None,
        default=None,
        mandatory=False,
        max_items=1,
        item_separator=",",
        regex=None,
        version=1,
        help="No help available.",
        print_format="%s",
        impact=Parameter.Impact.affects_values,
    ):

class ParameterDictionary(dict):
    """Directory holding all plugin parameters for a ``Freva`` plugin.
    This class behaves like a built-in ``dict`` with additional features.
    The most prominent feature is that the order of added items is preserved,
    as opposed to a normal build-in ``dict``.
    """
    def __init__(self, *parameters: ParameterType) -> None:

class _ConfigWrapper:
    """Convenience class that helps to dynamically set the location of the
    evaluation system config file."""
    _env: str = "EVALUATION_SYSTEM_CONFIG_FILE"
    def __init__(
        self,
        default_file: str,
    ):
        self.default_file = default_file
    def __fspath__(self) -> str:
        return os.environ.get(self._env, self.default_file)
    def __repr__(self) -> str:
        return self.__fspath__()

from evaluation_system.api import plugin
class TemplatePlugin(plugin.PluginAbstract):
    __version__ = (0, 0, 0)
    """
    def __version__(self) -> tuple[int, int, int]:
        # 3-value tuple representing the plugin version.
    """
    __short_description__: str = "template plugin"
    __category__ = "something"
    """
    def __category__(self) -> str:
        # Optional category this plugin belongs to.
        return ""
    """
    __tags__ = ["something", "somethingelse"]
    """
    def __tags__(self) -> list[str]:
        # Optional tags, that are the plugin can be described with.
        return [""]
    """
    tool_developer: Optional[str] = "someonename someonefamily"
    __long_description__: Optional[str] = "template plugin long"

from evaluation_system.api.parameters import ParameterDictionary, String, Bool
class TemplatePlugin(plugin.PluginAbstract):
    __parameters__ = ParameterDictionary(
        String(ParameterType),
        """
        Example:
            String(
                name="string",
                default="None",
                help=(
                    "some helps"
                ),
            )
        """
        Bool(ParameterType),
        """
        Example:
            Bool(
                name="checkbox",
                default=True,
            )
        """
    )

from evaluation_system.api.parameters import ParameterDictionary, SolrField, InputDirectory, String
class TemplatePlugin(plugin.PluginAbstract):
    __parameters__ = ParameterDictionary(     
        InputDirectory(String),
        """
        Example:
            InputDirectory(
                name="inputdirectory",
            ),
        """
        SolrField(String),
        """
        class SolrField(String):
            # A parameter using solr for finding valid values.
            def __init__(
                self,
                *args,
                facet: str,
                group: int = 1,
                multiple: bool = False,
                predefined_facets: Optional[list[str]] = None,
                editable: bool = True,
                **kwargs,
            ): 
        """
    )

from evaluation_system.api.parameters import ParameterDictionary, String, CacheDirectory, SelectField, Directory
class TemplatePlugin(plugin.PluginAbstract):
    __parameters__ = ParameterDictionary(
        Directory(String),
        CacheDirectory(Directory),
        SelectField(String),
        """
        class SelectField(String):
            # Select field to select parameter from predefined values.
            def __init__(self, options: dict[str, str], *args, **kwargs):
        Example:
        SelectField(
            options={"first": "1st", "second": "2nd"},
        ),
        """
        Integer(ParameterType),
        """
        Example:
            Integer(
                name="integer",
                default=1,
            )
        """
    )

from evaluation_system.api import plugin
class TemplatePlugin(plugin.PluginAbstract):
    def run_tool(self, config_dict=None):
        self.call(f"python template_plugin.py arg1 arg2 {config_dict}")
        self.call(f"template_runner.sh {config_dict}")
        self.add_output_to_databrowser(
            output_dir,
            project=config_dict["project"], # user-<user-id>
            product=config_dict["product"], # f"{config_dict["project"]}.{config_dict["project"]}"
            institute=config_dict["institute"],
            model=config_dict["model"],
            experiment=config_dict["experiment"],
            time_frequency=config_dict["time_frequency"],
            variable=config_dict["variable"],
            ensemble=config_dict["ensemble"],
        )
        return self.prepare_output(config_dict["outputdir"])

from evaluation_system.api import plugin
import json
class TemplatePlugin(plugin.PluginAbstract):
    def run_tool(self, config_dict=None):
        json_file = Path(config_dict["cache"]) / "out.json"
        with json_file.open("w") as json_f:
            json.dump(config_dict, json_f, indent=4)
        with errorfile.open("w") as error_f:
            self.call(
                f"{self.class_basedir}/main_runner.sh {json_file}",
                stderr=error_f,
            )

import json
import sys
with open(sys.argv[1]) as f:
    config_dict = json.load(f)

channels:
    - conda-forge
dependencies:
    - r-base
    - pip

env:
	@# Installs a conda environment with R and the IDF package
	@if [ -d "./plugin_env" ]; then \
		rm -rf ./plugin_env; \
	fi
	conda env create --prefix ./plugin_env -f environment.yml --force
	Rscript -e 'install.packages("IDF", repos="https://CRAN.R-project.org/")'
cartopy:
	@# Download various cartopy shape-files
	@if [ -d "./cartopy" ]; then \
		rm -rf ./cartopy; \
	fi
	./plugin_env/bin/python3 assets/cartopy_download.py physical cultural
.PHONY: env cartopy

ssh <username>@levante.dkrz.de
#After login to Levante
cd work/ch1187/clint/freva-dev/share/work/<username>/freva-dev/
git clone https://gitlab.dkrz.de/freva/plugins4freva/plugin_workshop/example_plugin.git

Variables	Description
USER_BASE_DIR	Absolute path to the central directory for this user.
USER_OUTPUT_DIR	Absolute path to where the plugin outputs for this user are stored.
USER_PLOTS_DIR	Absolute path to where the plugin plots for this user are stored.
USER_CACHE_DIR	Absolute path to the cached data (temp data) for this user.
USER_UID	The users’ User Identifier.
SYSTEM_DATE	Current date in the form YYYYMMDD (e.g. 20120130).
SYSTEM_DATETIME	Current date in the form YYYYMMDD_HHmmSS (e.g. 20120130_101123).
SYSTEM_TIMESTAMP	Milliseconds since epoch (i.e. e.g. 1358929581838).
SYSTEM_RANDOM_UUID	A random Universal Unique Identifier (e.g. 912cca21-6364-4f46-9b03-4263410c9899).

Freva: Plugin Development¶

Overview of a Freva plugin¶

Why should I build a Freva plugin?¶

Structure of a Plugin¶

Structure of a Plugin: The Wrapper¶

Structure of a Plugin: The tool¶

Structure of a Plugin: Installer¶

Git and Gitlab¶

What is git?

What is gitlab?

Gitlab and Freva:¶

Gitlab and Freva: location of the plugins¶

Gitlab and Freva: cloning a repository¶

Gitlab and Freva: setting your SSH key¶

Gitlab and Freva: creating a new project¶

License of Plugins¶

What kind of License should I follow?¶

What kind of License should I follow?¶

Connecting your IDE / Code Editor to a remote session using SSH¶

1. VS-Code

2. PyCharm

3. R Studio

What is a Freva Wrapper?¶

Freva Wrapper Main Classes

Special Variables:¶

PluginAbstract Class¶

Function: class_basedir¶

PluginAbstract Class¶

Function: call¶

PluginAbstract Class¶

Function: call and class_basedir - Example¶

PluginAbstract Class¶

Function: add_output_to_databrowser¶

PluginAbstract Class¶

Function: add_output_to_databrowser - Example¶

How to find it in Freva:¶

PluginAbstract Class¶

Function: prepare_output¶

PluginAbstract Class¶

Function: prepare_output - Example¶

ParameterType Class¶

ParameterDictionary Class¶

_ConfigWrapper class¶

Freva Wrapper Structure

Freva Wrapper Structure: 1. Details¶

Freva Wrapper Structure: 2. Parameters¶

Freva Wrapper Structure: 2. Parameters¶

Freva Wrapper Structure: 2. Parameters¶

Freva Wrapper Structure: 3. Methods¶

Recommended: Keep track of errors¶

Additional: How to deal with JSON files in the main script of plugin¶

Python:¶

Bash¶

Wrapper Illustration¶

Wrapper Illustration¶

Wrapper Illustration¶

Wrapper Illustration¶

How To Install All Needed Libraries Of A Plugin¶

Why the need?¶

Steps to Install Necessary Packages

Define an Env YAML file¶

Install env via Conda¶

Activate Environment¶

More flexible approach via Makefile¶

How To Plug a Tool into Freva¶

Plug a Tool into Freva

Plug a tool into Freva¶

Plug a tool into Freva¶

Plug a tool into Freva¶

Plug a tool into Freva¶